From 00bfad10f82a0b5554a96e37aed7187c6f374112 Mon Sep 17 00:00:00 2001 From: Wei Liu Date: Tue, 13 May 2014 22:53:49 +0100 Subject: [PATCH] libxl.h: document the paradigm of using libxl types Signed-off-by: Wei Liu Acked-by: Ian Campbell --- tools/libxl/libxl.h | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h index c7aa817762..896ecabdf3 100644 --- a/tools/libxl/libxl.h +++ b/tools/libxl/libxl.h @@ -245,6 +245,16 @@ * libxl_types.idl). The library provides a common set of methods for * initialising and freeing these types. * + * IDL-generated libxl types should be used as follows: the user must + * always call the "init" function before using a type, even if the + * variable is simply being passed by reference as an out parameter + * to a libxl function. The user must always calls "dispose" exactly + * once afterwards, to clean up, regardless of whether operations on + * this object succeeded or failed. See the xl code for examples. + * + * "init" is idempotent. We intend that "dispose" will become + * idempotent, but this is not currently the case. + * * void libxl__init( *p): * * Initialises the members of "p" to all defaults. These may either -- 2.30.2